Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/pcl/docs.lha/cmu-user/cmu-user.info-9

Text File | 1992-08-05 | 53KB | 1,571 lines

Info file: cmu-user.info,    -*-Text-*-
produced by latexinfo-format-buffer
from file: cmu-user.tex



File: cmu-user.info  Node: Connecting Servers and Clients, Prev: The REMOTE Package, Up: The REMOTE Package, Next: Remote Evaluations

Connecting Servers and Clients
------------------------------


Before a client can connect to a server, it must know the network address on
which the server accepts connections.  Network addresses consist of a host
address or name, and a port number.  Host addresses are either a string of the
form `VANCOUVER.SLISP.CS.CMU.EDU' or a 32 bit unsigned integer.  Port
numbers are 16 bit unsigned integers.  Note: PORT in this context has
nothing to do with Mach ports and message passing.

When a process wants to receive connection requests (that is, become a
server), it first picks an integer to use as the port.  Only one server
(Lisp or otherwise) can use a given port number on a given machine at
any particular time.  This can be an iterative process to find a free
port: picking an integer and calling `create-request-server'.  This
function signals an error if the chosen port is unusable.  You will
probably want to write a loop using `handler-case', catching
conditions of type error, since this function does not signal more
specific conditions.


  -- Function: create-request-server
 PORT &optional ON-CONNECT

     `create-request-server' sets up the current Lisp to accept connections on
     the given port.  If port is unavailable for any reason, this signals an error.
     When a client connects to this port, the acceptance mechanism makes a wire
     structure and invokes the ON-CONNECT function.  Invoking this function has
     a couple purposes, and ON-CONNECT may be nil in which case the system
     foregoes invoking any function at connect time.

     The ON-CONNECT function is both a hook that allows you access to the wire
     created by the acceptance mechanism, and it confirms the connection.  This
     function takes two arguments, the wire and the host address of the connecting
     process.  See the section on host addresses below.  When ON-CONNECT is
     nil, the request server allows all connections.  When it is non-nil, the
     function returns two values, whether to accept the connection and a function
     the system should call when the connection terminates.  Either value may be
     nil, but when the first value is nil, the acceptance mechanism destroys the
     wire.

     `create-request-server' returns an object that `destroy-request-server'
     uses to terminate a connection.



 -- Function: destroy-request-server SERVER

     `destroy-request-server' takes the result of `create-request-server' and
     terminates that server.  Any existing connections remain intact, but all
     additional connection attempts will fail.



  -- Function: connect-to-remote-server
 HOST PORT &optional ON-DEATH

     `connect-to-remote-server' attempts to connect to a remote server at the
     given PORT on HOST and returns a wire structure if it is successful.
     If ON-DEATH is non-nil, it is a function the system invokes when this
     connection terminates.




File: cmu-user.info  Node: Remote Evaluations, Prev: Connecting Servers and Clients, Up: The REMOTE Package, Next: Remote Objects

Remote Evaluations
------------------

After the server and client have connected, they each have a wire allowing
function evaluation in the other process.  This RPC mechanism has three
flavors: for side-effect only, for a single value, and for multiple values.

Only a limited number of data types can be sent across wires as arguments for
remote function calls and as return values: integers inclusively less than 32
bits in length, symbols, lists, and REMOTE-OBJECTS (?).  The system sends symbols as two strings, the package name
and the symbol name, and if the package doesn't exist remotely, the remote
process signals an error.  The system ignores other slots of symbols.  Lists
may be any tree of the above valid data types.  To send other data types you
must represent them in terms of these supported types.  For example, you could
use `prin1-to-string' locally, send the string, and use `read-from-string'
remotely.


 -- Macro: remote wire {call-specs}*

     The `remote' macro arranges for the process at the other end of WIRE to
     invoke each of the functions in the CALL-SPECS.  To make sure the system
     sends the remote evaluation requests over the wire, you must call
     `wire-force-output'.

     Each of CALL-SPECS looks like a function call textually, but it has some
     odd constraints and semantics.  The function position of the form must be the
     symbolic name of a function.  `remote' evaluates each of the argument
     subforms for each of the CALL-SPECS locally in the current context, sending
     these values as the arguments for the functions.

     Consider the following example:
     (defun write-remote-string (str)
       (declare (simple-string str))
       (wire:remote wire
         (write-string str))) The value of `str' in the local process is
     passed over the wire with a request to invoke `write-string' on the
     value.  The system does not expect to remotely evaluate `str' for a
     value in the remote process.



 -- Function: wire-force-output WIRE

     `wire-force-output' flushes all internal buffers associated with
     WIRE, sending the remote requests.  This is necessary after a call
     to `remote'.



 -- Macro: remote-value wire call-spec

     The `remote-value' macro is similar to the `remote' macro.
     `remote-value' only takes one CALL-SPEC, and it returns the value
     returned by the function call in the remote process.  The value
     must be a valid type the system can send over a wire, and there is
     no need to call `wire-force-output' in conjunction with this
     interface.

     If client unwinds past the call to `remote-value', the server
     continues running, but the system ignores the value the server
     sends back.

     If the server unwinds past the remotely requested call, instead of
     returning normally, `remote-value' returns two values, nil and
     true.  Otherwise this returns the result of the remote evaluation
     and nil.



  -- Macro: remote-value-bind
  wire ({variable}*) remote-form {local-forms}*

     `remote-value-bind' is similar to `multiple-value-bind' except the
     values bound come from REMOTE-FORM's evaluation in the remote
     process.  The LOCAL-FORMS execute in an implicit `progn'.

     If the client unwinds past the call to `remote-value-bind', the
     server continues running, but the system ignores the values the
     server sends back.

     If the server unwinds past the remotely requested call, instead of
     returning normally, the LOCAL-FORMS never execute, and
     `remote-value-bind' returns nil.




File: cmu-user.info  Node: Remote Objects, Prev: Remote Evaluations, Up: The REMOTE Package, Next: Host Addresses

Remote Objects
--------------


The wire mechanism only directly supports a limited number of data types
for transmission as arguments for remote function calls and as return
values: integers inclusively less than 32 bits in length, symbols,
lists.  Sometimes it is useful to allow remote processes to refer to
local data structures without allowing the remote process to operate on
the data.  We have REMOTE-OBJECTS to support this without the need to
represent the data structure in terms of the above data types, to send
the representation to the remote process, to decode the representation,
to later encode it again, and to send it back along the wire.

You can convert any Lisp object into a remote-object.  When you send a
remote-object along a wire, the system simply sends a unique token for
it.  In the remote process, the system looks up the token and returns a
remote-object for the token.  When the remote process needs to refer to
the original Lisp object as an argument to a remote call back or as a
return value, it uses the remote-object it has which the system converts
to the unique token, sending that along the wire to the originating
process.  Upon receipt in the first process, the system converts the
token back to the same (`eq') remote-object.


 -- Function: make-remote-object OBJECT

     `make-remote-object' returns a remote-object that has OBJECT as its
     value.  The remote-object can be passed across wires just like the
     directly supported wire data types.



 -- Function: remote-object-p OBJECT

     The function `remote-object-p' returns true if OBJECT is a remote
     object and nil otherwise.



 -- Function: remote-object-local-p REMOTE

     The function `remote-object-local-p' returns true if REMOTE refers
     to an object in the local process.  This is can only occur if the
     local process created REMOTE with `make-remote-object'.



 -- Function: remote-object-eq obj1 obj2

     The function `remote-object-eq' returns true if obj1 and obj2 refer
     to the same (`eq') lisp object, regardless of which process created
     the remote-objects.



 -- Function: remote-object-value REMOTE

     This function returns the original object used to create the given
     remote object.  It is an error if some other process originally
     created the remote-object.



 -- Function: forget-remote-translation OBJECT

     This function removes the information and storage necessary to
     translate remote-objects back into OBJECT, so the next `gc' can
     reclaim the memory.  You should use this when you no longer expect
     to receive references to OBJECT.  If some remote process does send
     a reference to OBJECT, `remote-object-value' signals an error.




File: cmu-user.info  Node: Host Addresses, Prev: Remote Objects, Up: The REMOTE Package

Host Addresses
--------------

The operating system maintains a database of all the valid host
addresses.  You can use this database to convert between host names and
addresses and vice-versa.


 -- Function: lookup-host-entry HOST

     `lookup-host-entry' searches the database for the given HOST and
     returns a host-entry structure for it.  If it fails to find HOST in
     the database, it returns nil.  HOST is either the address (as an
     integer) or the name (as a string) of the desired host.



 -- Function: host-entry-name HOST-ENTRY

 -- Function: host-entry-aliases HOST-ENTRY

 -- Function: host-entry-addr-list HOST-ENTRY

 -- Function: host-entry-addr HOST-ENTRY

     `host-entry-name', `host-entry-aliases', and `host-entry-addr-list'
     each return the indicated slot from the host-entry structure.
     `host-entry-addr' returns the primary (first) address from the list
     returned by `host-entry-addr-list'.




File: cmu-user.info  Node: The WIRE Package, Prev: The REMOTE Package, Up: Interprocess Communication under LISP, Next: Out-Of-Band Data

The WIRE Package
================


The `wire' package provides for sending data along wires.  The `remote'
package sits on top of this package.  All data sent with a given output
routine must be read in the remote process with the complementary
fetching routine.  For example, if you send so a string with
`wire-output-string', the remote process must know to use
`wire-get-string'.  To avoid rigid data transfers and complicated code,
the interface supports sending TAGGED data.  With tagged data, the
system sends a tag announcing the type of the next data, and the remote
system takes care of fetching the appropriate type.

When using interfaces at the wire level instead of the RPC level, the
remote process must read everything sent by these routines.  If the
remote process leaves any input on the wire, it will later mistake the
data for an RPC request causing unknown lossage.

* Menu:

* Untagged Data::
* Tagged Data::
* Making Your Own Wires::



File: cmu-user.info  Node: Untagged Data, Prev: The WIRE Package, Up: The WIRE Package, Next: Tagged Data

Untagged Data
-------------

When using these routines both ends of the wire know exactly what types are
coming and going and in what order. This data is restricted to the following
types:

   * 8 bit unsigned bytes.

   * 32 bit unsigned bytes.

   * 32 bit integers.

   * simple-strings less than 65535 in length.




 -- Function: wire-output-byte wire byte

 -- Function: wire-get-byte WIRE

 -- Function: wire-output-number wire number

 -- Function: wire-get-number WIRE &optional SIGNED

 -- Function: wire-output-string wire string

 -- Function: wire-get-string WIRE

     These functions either output or input an object of the specified
     data type.  When you use any of these output routines to send data
     across the wire, you must use the corresponding input routine
     interpret the data.




File: cmu-user.info  Node: Tagged Data, Prev: Untagged Data, Up: The WIRE Package, Next: Making Your Own Wires

Tagged Data
-----------

When using these routines, the system automatically transmits and
interprets the tags for you, so both ends can figure out what kind of
data transfers occur.  Sending tagged data allows a greater variety of
data types: integers inclusively less than 32 bits in length, symbols,
lists, and REMOTE-OBJECTS (*Note Remote Objects::).  The system sends
symbols as two strings, the package name and the symbol name, and if the
package doesn't exist remotely, the remote process signals an error.
The system ignores other slots of symbols.  Lists may be any tree of the
above valid data types.  To send other data types you must represent
them in terms of these supported types.  For example, you could use
`prin1-to-string' locally, send the string, and use `read-from-string'
remotely.


 -- Function: wire-output-object wire object &optional CACHE-IT

 -- Function: wire-get-object WIRE

     The function `wire-output-object' sends OBJECT over WIRE preceded
     by a tag indicating its type.

     If CACHE-IT is non-nil, this function only sends OBJECT the first
     time it gets OBJECT.  Each end of the wire associates a token with
     OBJECT, similar to remote-objects, allowing you to send the object
     more efficiently on successive transmissions.  CACHE-IT defaults to
     true for symbols and nil for other types.  Since the RPC level
     requires function names, a high-level protocol based on a set of
     function calls saves time in sending the functions' names
     repeatedly.

     The function `wire-get-object' reads the results of
     `wire-output-object' and returns that object.




File: cmu-user.info  Node: Making Your Own Wires, Prev: Tagged Data, Up: The WIRE Package

Making Your Own Wires
---------------------

You can create wires manually in addition to the `remote' package's
interface creating them for you.  To create a wire, you need a Unix file
descriptor.  If you are unfamiliar with Unix file descriptors, see
section 2 of the Unix manual pages.


 -- Function: make-wire DESCRIPTOR

     The function `make-wire' creates a new wire when supplied with the
     file descriptor to use for the underlying I/O operations.



 -- Function: wire-p OBJECT

     This function returns true if OBJECT is indeed a wire, nil
     otherwise.



 -- Function: wire-fd WIRE

     This function returns the file descriptor used by the WIRE.




File: cmu-user.info  Node: Out-Of-Band Data, Prev: The WIRE Package, Up: Interprocess Communication under LISP

Out-Of-Band Data
================


The TCP/IP protocol allows users to send data asynchronously, otherwise
known as OUT-OF-BAND data.  When using this feature, the operating
system interrupts the receiving process if this process has chosen to be
notified about out-of-band data.  The receiver can grab this input
without affecting any information currently queued on the socket.
Therefore, you can use this without interfering with any current
activity due to other wire and remote interfaces.

Unfortunately, most implementations of TCP/IP are broken, so use of
out-of-band data is limited for safety reasons.  You can only reliably
send one character at a time.

This routines in this section provide a mechanism for establishing
handlers for out-of-band characters and for sending them out-of-band.
These all take a Unix file descriptor instead of a wire, but you can
fetch a wire's file descriptor with `wire-fd'.


 -- Function: add-oob-handler fd char handler

     The function `add-oob-handler' arranges for HANDLER to be called
     whenever CHAR shows up as out-of-band data on the file descriptor
     FD.



 -- Function: remove-oob-handler fd char

     This function removes the handler for the character CHAR on the
     file descriptor FD.



 -- Function: remove-all-oob-handlers FD

     This function removes all handlers for the file descriptor FD.



 -- Function: send-character-out-of-band fd char

     This function Sends the character CHAR down the file descriptor FD
     out-of-band.





File: cmu-user.info  Node: Debugger Programmer's Interface, Prev: Interprocess Communication under LISP, Up: Top, Next: Function Index

Debugger Programmer's Interface
*******************************


The debugger programmers interface is exported from from the
`"DEBUG-INTERNALS"' or `"DI"' package.  This is a CMU extension that
allows debugging tools to be written without detailed knowledge of the
compiler or run-time system.

Some of the interface routines take a code-location as an argument.  As
described in the section on code-locations, some code-locations are
unknown.  When a function calls for a BASIC-CODE-LOCATION, it takes
either type, but when it specifically names the argument CODE-LOCATION,
the routine will signal an error if you give it an unknown
code-location.

* Menu:

* DI Exceptional Conditions::
* Debug-variables::
* Frames::
* Debug-functions::
* Debug-blocks::
* Breakpoints::
* Code-locations::
* Debug-sources::
* Source Translation Utilities::




File: cmu-user.info  Node: DI Exceptional Conditions, Prev: Debugger Programmer's Interface, Up: Debugger Programmer's Interface, Next: Debug-variables

DI Exceptional Conditions
=========================


Some of these operations fail depending on the availability debugging
information.  In the most severe case, when someone saved a Lisp image
stripping all debugging data structures, no operations are valid.  In
this case, even backtracing and finding frames is impossible.  Some
interfaces can simply return values indicating the lack of information,
or their return values are naturally meaningful in light missing data.
Other routines, as documented below, will signal `serious-condition's
when they discover awkward situations.  This interface does not provide
for programs to detect these situations other than by calling a routine
that detects them and signals a condition.  These are serious-conditions
because the program using the interface must handle them before it can
correctly continue execution.  These debugging conditions are not errors
since it is no fault of the programmers that the conditions occur.

* Menu:

* Debug-conditions::
* Debug-errors::



File: cmu-user.info  Node: Debug-conditions, Prev: DI Exceptional Conditions, Up: DI Exceptional Conditions, Next: Debug-errors

Debug-conditions
----------------


The debug internals interface signals conditions when it can't adhere
to its contract.  These are serious-conditions because the program
using the interface must handle them before it can correctly continue
execution.  These debugging conditions are not errors since it is no
fault of the programmers that the conditions occur.  The interface
does not provide for programs to detect these situations other than
calling a routine that detects them and signals a condition.




 -- Condition: debug-condition
     This condition inherits from serious-condition, and all debug-conditions
     inherit from this.  These must be handled, but they are not programmer errors.





 -- Condition: no-debug-info
     This condition indicates there is absolutely no debugging information
     available.





 -- Condition: no-debug-function-returns
     This condition indicates the system cannot return values from a frame since
     its debug-function lacks debug information details about returning values.




 -- Condition: no-debug-blocks
     This condition indicates that a function was not compiled with debug-block
     information, but this information is necessary necessary for some requested
     operation.



 -- Condition: no-debug-variables
     Similar to `no-debug-blocks', except that variable information was
     requested.



 -- Condition: lambda-list-unavailable
     Similar to `no-debug-blocks', except that lambda list information was
     requested.




 -- Condition: invalid-value
     This condition indicates a debug-variable has `:invalid' or `:unknown'
     value in a particular frame.





 -- Condition: ambiguous-variable-name
     This condition indicates a user supplied debug-variable name identifies more
     than one valid variable in a particular frame.




File: cmu-user.info  Node: Debug-errors, Prev: Debug-conditions, Up: DI Exceptional Conditions

Debug-errors
------------


These are programmer errors resulting from misuse of the debugging tools'
programmers' interface.  You could have avoided an occurrence of one of these
by using some routine to check the use of the routine generating the error.



 -- Condition: debug-error
     This condition inherits from error, and all user programming errors inherit
     from this condition.




 -- Condition: unhandled-condition
     This error results from a signalled `debug-condition' occurring
     without anyone handling it.




 -- Condition: unknown-code-location
     This error indicates the invalid use of an unknown-code-location.





 -- Condition: unknown-debug-variable
     This error indicates an attempt to use a debug-variable in conjunction with an
     inappropriate debug-function; for example, checking the variable's validity
     using a code-location in the wrong debug-function will signal this error.





 -- Condition: frame-function-mismatch
     This error indicates you called a function returned by
     `preprocess-for-eval'
     on a frame other than the one for which the function had been prepared.





File: cmu-user.info  Node: Debug-variables, Prev: DI Exceptional Conditions, Up: Debugger Programmer's Interface, Next: Frames

Debug-variables
===============


Debug-variables represent the constant information about where the system
stores argument and local variable values.  The system uniquely identifies with
an integer every instance of a variable with a particular name and package.  To
access a value, you must supply the frame along with the debug-variable since
these are particular to a function, not every instance of a variable on the
stack.


 -- Function: debug-variable-name debug-variable

     This function returns the name of the DEBUG-VARIABLE.  The name is the
     name of the symbol used as an identifier when writing the code.




 -- Function: debug-variable-package debug-variable

     This function returns the package name of the DEBUG-VARIABLE.  This is
     the package name of the symbol used as an identifier when writing the code.




 -- Function: debug-variable-symbol debug-variable

     This function returns the symbol from interning `debug-variable-name' in
     the package named by `debug-variable-package'.




 -- Function: debug-variable-id debug-variable

     This function returns the integer that makes DEBUG-VARIABLE's name and
     package name unique with respect to other DEBUG-VARIABLE's in the same
     function.




 -- Function: debug-variable-validity debug-variable basic-code-location

     This function returns three values reflecting the validity of
     DEBUG-VARIABLE's value at BASIC-CODE-LOCATION:
             `:valid'

           The value is known to be available.
             `:invalid'

           The value is known to be unavailable.
             `:unknown'

           The value's availability is unknown.





 -- Function: debug-variable-value debug-variable frame

     This function returns the value stored for DEBUG-VARIABLE in FRAME.
     The value may be invalid.  This is `SETF''able.




 -- Function: debug-variable-valid-value debug-variable frame

     This function returns the value stored for DEBUG-VARIABLE in
     FRAME.  If the value is not `:valid', then this signals an
     `invalid-value' error.





File: cmu-user.info  Node: Frames, Prev: Debug-variables, Up: Debugger Programmer's Interface, Next: Debug-functions

Frames
======


Frames describe a particular call on the stack for a particular thread.  This
is the environment for name resolution, getting arguments and locals, and
returning values.  The stack conceptually grows up, so the top of the stack is
the most recently called function.

`top-frame', `frame-down', `frame-up', and
`frame-debug-function' can only fail when there is absolutely no
debug information available.  This can only happen when someone saved a
Lisp image specifying that the system dump all debugging data.



 -- Function: top-frame
     This function never returns the frame for itself, always the frame before
     calling `top-frame'.




 -- Function: frame-down frame

     This returns the frame immediately below FRAME on the stack.  When
     FRAME is the bottom of the stack, this returns nil.




 -- Function: frame-up frame

     This returns the frame immediately above FRAME on the stack.  When
     FRAME is the top of the stack, this returns nil.




 -- Function: frame-debug-function frame

     This function returns the debug-function for the function whose call
     FRAME represents.




 -- Function: frame-code-location frame

     This function returns the code-location where FRAME's debug-function will
     continue running when program execution returns to FRAME.  If someone
     interrupted this frame, the result could be an unknown code-location.




 -- Function: frame-catches frame

     This function returns an a-list for all active catches in FRAME mapping
     catch tags to the code-locations at which the catch re-enters.




 -- Function: eval-in-frame frame form

     This evaluates FORM in FRAME's environment.  This can signal
     several different debug-conditions since its success relies on a variety of
     inexact debug information: `invalid-value',
     `ambiguous-variable-name', `frame-function-mismatch'.  See
     also preprocess-for-eval ?.




 -- Function: return-from-frame frame values

     This returns the elements in the list VALUES as multiple values from
     FRAME as if the function FRAME represents returned these values.
     This signals a `no-debug-function-returns' condition when FRAME's
     debug-function lacks information on returning values.

     Not Yet Implemented




File: cmu-user.info  Node: Debug-functions, Prev: Frames, Up: Debugger Programmer's Interface, Next: Debug-blocks

{Debug-functions}
=================

Debug-functions represent the static information about a function determined at
compile time --- argument and variable storage, their lifetime information,
etc.  The debug-function also contains all the debug-blocks representing
basic-blocks of code, and these contains information about specific
code-locations in a debug-function.



 -- Macro: do-debug-function-blocks (block-var debug-function [result-form]) {form}*

     This executes the forms in a context with BLOCK-VAR bound to each
     debug-block in DEBUG-FUNCTION successively.  RESULT-FORM is
     an optional form to execute for a return value, and
     `do-debug-function-blocks' returns nilif there is no
     RESULT-FORM.  This signals a `no-debug-blocks' condition when the
     DEBUG-FUNCTION lacks debug-block information.




 -- Function: debug-function-lambda-list debug-function

     This function returns a list representing the lambda-list for
     DEBUG-FUNCTION.  The list has the following structure:

             (required-var1 required-var2
              ...
              (:optional var3 suppliedp-var4)
              (:optional var5)
              ...
              (:rest var6) (:rest var7)
              ...
              (:keyword keyword-symbol var8 suppliedp-var9)
              (:keyword keyword-symbol var10)
              ...
              )

     Each `var'N is a debug-variable; however, the symbol
     `:deleted' appears instead whenever the argument remains unreferenced
     throughout DEBUG-FUNCTION.

     If there is no lambda-list information, this signals a
     `lambda-list-unavailable' condition.




 -- Macro: do-debug-function-variables (var debug-function [result]) {form}*

     This macro executes each FORM in a context with VAR bound to each
     debug-variable in DEBUG-FUNCTION.  This returns the value of executing
     RESULT (defaults to nil).  This may iterate over only some of
     DEBUG-FUNCTION's variables or none depending on debug policy; for example,
     possibly the compilation only preserved argument information.




 -- Function: debug-variable-info-available debug-function

     This function returns whether there is any variable information for
     DEBUG-FUNCTION.  This is useful for distinguishing whether there were no
     locals in a function or whether there was no variable information.  For
     example, if `do-debug-function-variables' executes its forms zero times,
     then you can use this function to determine the reason.




 -- Function: debug-function-symbol-variables debug-function symbol

     This function returns a list of debug-variables in DEBUG-FUNCTION having
     the same name and package as SYMBOL.  If SYMBOL is uninterned, then
     this returns a list of debug-variables without package names and with the same
     name as SYMBOL.  The result of this function is limited to the
     availability of variable information in DEBUG-FUNCTION; for example,
     possibly DEBUG-FUNCTION only knows about its arguments.




 -- Function: ambiguous-debug-variables debug-function name-prefix-string

     This function returns a list of debug-variables in DEBUG-FUNCTION whose
     names contain NAME-PREFIX-STRING as an initial substring.  The result of
     this function is limited to the availability of variable information in
     DEBUG-FUNCTION; for example, possibly DEBUG-FUNCTION only knows
     about its arguments.




 -- Function: preprocess-for-eval form basic-code-location

     This function returns a function of one argument that evaluates FORM in
     the lexical context of BASIC-CODE-LOCATION.  This allows efficient
     repeated evaluation of FORM at a certain place in a function which could
     be useful for conditional breaking.  This signals a `no-debug-variables'
     condition when the code-location's debug-function has no debug-variable
     information available.  The returned function takes a frame as an
     argument.  See also eval-in-frame *Note Frames::.




 -- Function: function-debug-function function

     This function returns a debug-function that represents debug information for
     FUNCTION.




 -- Function: debug-function-kind debug-function

     This function returns the kind of function DEBUG-FUNCTION represents.
     The value is one of the following:
     `:optional'

          This kind of function is an entry point to an ordinary function.  It handles
          optional defaulting, parsing keywords, etc.
     `:external'

          This kind of function is an entry point to an ordinary function.  It checks
          argument values and count and calls the defined function.
     `:top-level'

          This kind of function executes one or more random top-level forms
          from a file.
     `:cleanup'

          This kind of function represents the cleanup forms in an `unwind-protect'.
     nil
          This kind of function is not one of the above; that is, it is not specially
          marked in any way.





 -- Function: debug-function-function debug-function

     This function returns the Common Lisp function associated with the
     DEBUG-FUNCTION.  This returns nilif the function is unavailable or is
     non-existent as a user callable function object.




 -- Function: debug-function-name debug-function

     This function returns the name of the function represented by
     DEBUG-FUNCTION.  This may be a string or a cons; do not assume it is a symbol.





File: cmu-user.info  Node: Debug-blocks, Prev: Debug-functions, Up: Debugger Programmer's Interface, Next: Breakpoints

Debug-blocks
============


Debug-blocks contain information pertinent to a specific range of code in a
debug-function.


 -- Macro: do-debug-block-locations (code-var debug-block [result]) {form}*

     This macro executes each FORM in a context with CODE-VAR bound to
     each code-location in DEBUG-BLOCK.  This returns the value of executing
     RESULT (defaults to nil).




 -- Function: debug-block-successors debug-block

     This function returns the list of possible code-locations where execution may
     continue when the basic-block represented by DEBUG-BLOCK completes its
     execution.




 -- Function: debug-block-elsewhere-p debug-block

     This function returns whether DEBUG-BLOCK represents elsewhere code.
     This is code the compiler has moved out of a function's code sequence for
     optimization reasons.  Code-locations in these blocks are unsuitable for
     stepping tools, and the first code-location has nothing to do with a normal
     starting location for the block.





File: cmu-user.info  Node: Breakpoints, Prev: Debug-blocks, Up: Debugger Programmer's Interface, Next: Code-locations

Breakpoints
===========


A breakpoint represents a function the system calls with the current frame when
execution passes a certain code-location.  A break point is active or inactive
independent of its existence.  They also have an extra slot for users to tag
the breakpoint with information.


 -- Function: make-breakpoint hook-function what
             &keys :kind :info :function-end-cookie

     This function creates and returns a breakpoint.  When program execution
     encounters the breakpoint, the system calls HOOK-FUNCTION.
     HOOK-FUNCTION takes the current frame for the function in which the
     program is running and the breakpoint object.

     WHAT and KIND determine where in a function the system invokes
     HOOK-FUNCTION.  WHAT is either a code-location or a
     debug-function.  KIND is one of `:code-location',
     `:function-start', or `:function-end'.  Since the starts and ends of
     functions may not have code-locations representing them, designate these places
     by supplying WHAT as a debug-function and KIND indicating the
     `:function-start' or `:function-end'.  When WHAT is a
     debug-function and KIND is `:function-end', then hook-function must
     take two additional arguments, a list of values returned by the function and a
     function-end-cookie.

     INFO is information supplied by and used by the user.

     FUNCTION-END-COOKIE is a function.  To implement function-end
     breakpoints, the system uses starter breakpoints to establish the function-end
     breakpoint for each invocation of the function.  Upon each entry, the system
     creates a unique cookie to identify the invocation, and when the user supplies
     a function for this argument, the system invokes it on the cookie.  The system
     later invokes the function-end breakpoint hook on the same cookie.  The user
     may save the cookie when passed to the function-end-cookie function for
     later comparison in the hook function.

     This signals an error if WHAT is an unknown code-location.




 -- Function: activate-breakpoint breakpoint

     This function causes the system to invoke the BREAKPOINT's hook-function
     until the next call to `deactivate-breakpoint' or `delete-breakpoint'.
     The system invokes breakpoint hook functions in the opposite order that you
     activate them.




 -- Function: deactivate-breakpoint breakpoint

     This function stops the system from invoking the BREAKPOINT's
     hook-function.




 -- Function: breakpoint-active-p breakpoint

     This returns whether BREAKPOINT is currently active.




 -- Function: breakpoint-hook-function breakpoint

     This function returns the BREAKPOINT's function the system calls when
     execution encounters BREAKPOINT, and it is active.  This is
     `SETF''able.




 -- Function: breakpoint-info breakpoint

     This function returns BREAKPOINT's information supplied by the user.
     This is `SETF''able.




 -- Function: breakpoint-kind breakpoint

     This function returns the BREAKPOINT's kind specification.




 -- Function: breakpoint-what breakpoint

     This function returns the BREAKPOINT's what specification.




 -- Function: delete-breakpoint breakpoint

     This function frees system storage and removes computational overhead
     associated with BREAKPOINT.  After calling this, BREAKPOINT is
     useless and can never become active again.





File: cmu-user.info  Node: Code-locations, Prev: Breakpoints, Up: Debugger Programmer's Interface, Next: Debug-sources

Code-locations
==============


Code-locations represent places in functions where the system has correct
information about the function's environment and where interesting operations
can occur --- asking for a local variable's value, setting breakpoints,
evaluating forms within the function's environment, etc.

Sometimes the interface returns unknown code-locations.  These represent places
in functions, but there is no debug information associated with them.  Some
operations accept these since they may succeed even with missing debug data.
These operations' argument is named BASIC-CODE-LOCATION indicating they
take known and unknown code-locations.  If an operation names its argument
CODE-LOCATION, and you supply an unknown one, it will signal an error.
For example, `frame-code-location' may return an unknown code-location if
someone interrupted Lisp in the given frame.  The system knows where execution
will continue, but this place in the code may not be a place for which the
compiler dumped debug information.


 -- Function: code-location-debug-function basic-code-location

     This function returns the debug-function representing information about the
     function corresponding to the code-location.




 -- Function: code-location-debug-block basic-code-location

     This function returns the debug-block containing code-location if it is
     available.  Some debug policies inhibit debug-block information, and if none is
     available, then this signals a `no-debug-blocks' condition.




 -- Function: code-location-top-level-form-offset code-location

     This function returns the number of top-level forms before the one containing
     CODE-LOCATION as seen by the compiler in some compilation unit.  A
     compilation unit is not necessarily a single file, see the section on
     debug-sources.




 -- Function: code-location-form-number code-location

     This function returns the number of the form corresponding to
     CODE-LOCATION.  The form number is derived by walking the subforms of a
     top-level form in depth-first order.  While walking the top-level form, count
     one in depth-first order for each subform that is a cons.  See
     form-number-translations ?.




 -- Function: code-location-debug-source code-location

     This function returns CODE-LOCATION's debug-source.




 -- Function: code-location-unknown-p basic-code-location

     This function returns whether BASIC-CODE-LOCATION is unknown.  It returns
     nilwhen the code-location is known.




 -- Function: code-location= code-location1 code-location2

     This function returns whether the two code-locations are the same.





File: cmu-user.info  Node: Debug-sources, Prev: Code-locations, Up: Debugger Programmer's Interface, Next: Source Translation Utilities

Debug-sources
=============


Debug-sources represent how to get back the source for some code.  The source
is either a file (`compile-file' or `load'), a lambda-expression
(`compile', `defun', `defmacro'), or a stream (something
particular to CMU Common Lisp, `compile-from-stream').

When compiling a source, the compiler counts each top-level form it processes,
but when the compiler handles multiple files as one block compilation, the
top-level form count continues past file boundaries.  Therefore
`code-location-top-level-form-offset' returns an offset that does not
always start at zero for the code-location's debug-source.  The offset into a
particular source is `code-location-top-level-form-offset' minus
`debug-source-root-number'.

Inside a top-level form, a code-location's form number indicates the subform
corresponding to the code-location.


 -- Function: debug-source-from debug-source

     This function returns an indication of the type of source.  The following
     are the possible values:
     `:file'

          from a file (obtained by `compile-file' if compiled).
     `:lisp'

          from Lisp (obtained by `compile' if compiled).
     `:stream'

          from a non-file stream (CMU Common Lisp supports `compile-from-stream').





 -- Function: debug-source-name debug-source

     This function returns the actual source in some sense represented by
     debug-source, which is related to `debug-source-from':
     `:file'

          the pathname of the file.
     `:lisp'

          a lambda-expression.
     `:stream'

          some descriptive string that's otherwise useless.





 -- Function: debug-source-created debug-source

     This function returns the universal time someone created the source.  This
     may be nilif it is unavailable.




 -- Function: debug-source-compiled debug-source

     This function returns the time someone compiled the source.  This is nilif the source is uncompiled.




 -- Function: debug-source-root-number debug-source

     This returns the number of top-level forms processed by the compiler before
     compiling this source.  If this source is uncompiled, this is zero.  This may
     be zero even if the source is compiled since the first form in the first file
     compiled in one compilation, for example, must have a root number of zero ---
     the compiler saw no other top-level forms before it.




File: cmu-user.info  Node: Source Translation Utilities, Prev: Debug-sources, Up: Debugger Programmer's Interface

Source Translation Utilities
============================


These two functions provide a mechanism for converting the rather
obscure (but highly compact) representation of source locations into an
actual source form:


 -- Function: debug-source-start-positions debug-source

     This function returns the file position of each top-level form as an array if
     DEBUG-SOURCE is from a `:file'.  If `debug-source-from' is
     `:lisp' or `:stream', this returns nil.




 -- Function: form-number-translations form tlf-number

     This function returns a table mapping form numbers (see
     `code-location-form-number') to source-paths.  A source-path indicates a
     descent into the top-level-form FORM, going directly to the subform
     corresponding to a form number.  TLF-NUMBER is the top-level-form number
     of FORM.




 -- Function: source-path-context form path context

     This function returns the subform of FORM indicated by the source-path.
     FORM is a top-level form, and PATH is a source-path into it.
     CONTEXT is the number of enclosing forms to return instead of directly
     returning the source-path form.  When CONTEXT is non-zero, the
     form returned contains a marker, `', immediately
     before the form indicated by PATH.





File: cmu-user.info  Node: Function Index, Prev: Debugger Programmer's Interface, Up: Top, Next: Variable Index

Function Index
**************



* Menu:

* activate-breakpoint: Breakpoints.
* add-fd-handler: Using SERVE-EVENT with Unix File Descriptors.
* add-oob-handler: Out-Of-Band Data.
* addr: Alien Coercion Operations.
* add-xwindow-object: Object Sets.
* alien-funcall: alien-funcall.
* alien-sap: Alien Coercion Operations.
* ambiguous-debug-variables: Debug-functions.
* breakpoint-active-p: Breakpoints.
* breakpoint-hook-function: Breakpoints.
* breakpoint-info: Breakpoints.
* breakpoint-kind: Breakpoints.
* breakpoint-what: Breakpoints.
* cast: Alien Coercion Operations.
* clear-search-list: Search Lists.
* cmd-switch-name: Reading the Command Line.
* cmd-switch-value: Reading the Command Line.
* cmd-switch-words: Reading the Command Line.
* code-location=: Code-locations.
* code-location-debug-block: Code-locations.
* code-location-debug-function: Code-locations.
* code-location-debug-source: Code-locations.
* code-location-form-number: Code-locations.
* code-location-top-level-form-offset: Code-locations.
* code-location-unknown-p: Code-locations.
* compile: Calling the Compiler.
* compile-file: Calling the Compiler.
* compile-from-stream: Calling the Compiler.
* connect-to-remote-server: Connecting Servers and Clients.
* create-request-server: Connecting Servers and Clients.
* deactivate-breakpoint: Breakpoints.
* debug-block-elsewhere-p: Debug-blocks.
* debug-block-successors: Debug-blocks.
* debug-function-function: Debug-functions.
* debug-function-kind: Debug-functions.
* debug-function-lambda-list: Debug-functions.
* debug-function-name: Debug-functions.
* debug-function-symbol-variables: Debug-functions.
* debug-source-compiled: Debug-sources.
* debug-source-created: Debug-sources.
* debug-source-from: Debug-sources.
* debug-source-name: Debug-sources.
* debug-source-root-number: Debug-sources.
* debug-source-start-positions: Source Translation Utilities.
* debug-variable-id: Debug-variables.
* debug-variable-info-available: Debug-functions.
* debug-variable-name: Debug-variables.
* debug-variable-package: Debug-variables.
* debug-variable-symbol: Debug-variables.
* debug-variable-validity: Debug-variables.
* debug-variable-valid-value: Debug-variables.
* debug-variable-value: Debug-variables.
* def-alien-routine: def-alien-routine.
* def-alien-type: Defining Alien Types.
* def-alien-variable: External Alien Variables.
* default-interrupt: Changing Interrupt Handlers.
* def-source-context: Error Message Parameterization.
* delete-breakpoint: Breakpoints.
* deref: Alien Access Operations.
* describe: Describe.
* destroy-request-server: Connecting Servers and Clients.
* disable-clx-event-handling: Without Object Sets.
* do-debug-block-locations: Debug-blocks.
* do-debug-function-blocks: Debug-functions.
* do-debug-function-variables: Debug-functions.
* enable-clx-event-handling: Without Object Sets.
* enable-interrupt: Changing Interrupt Handlers.
* encapsulate: Encapsulation Functions.
* encapsulated-p: Encapsulation Functions.
* enumerate-search-list: Search Lists.
* eval-in-frame: Frames.
* extern-alien: External Alien Variables.
* fd-stream-fd: File Descriptor Streams.
* fd-stream-p: File Descriptor Streams.
* float-infinity-p: IEEE Special Values.
* float-nan-p: IEEE Special Values.
* float-normalized-p: Denormalized Floats.
* float-trapping-nan-p: IEEE Special Values.
* flush-display-events: Using SERVE-EVENT with the CLX Interface to X.
* forget-remote-translation: Remote Objects.
* format-decoded-time: Time Parsing and Formatting.
* format-universal-time: Time Parsing and Formatting.
* form-number-translations: Source Translation Utilities.
* frame-catches: Frames.
* frame-code-location: Frames.
* frame-debug-function: Frames.
* frame-down: Frames.
* frame-up: Frames.
* free-alien: Alien Dynamic Allocation.
* function-debug-function: Debug-functions.
* gc: Garbage Collection.
* gc-off: Garbage Collection.
* gc-on: Garbage Collection.
* get-bytes-consed: Additional Timing Utilities.
* get-floating-point-modes: Accessing the Floating Point Modes.
* get-unix-error-msg: Unix System Calls.
* gr-bind: Making Sense of Mach Return Codes.
* gr-call*: Making Sense of Mach Return Codes.
* gr-call: Making Sense of Mach Return Codes.
* gr-error: Making Sense of Mach Return Codes.
* host-entry-addr: Host Addresses.
* host-entry-addr-list: Host Addresses.
* host-entry-aliases: Host Addresses.
* host-entry-name: Host Addresses.
* ignore-interrupt: Changing Interrupt Handlers.
* inspect: The Inspector.
* int-sap: System Area Pointers.
* invalidate-descriptor: Using SERVE-EVENT with Unix File Descriptors.
* iterate: Local Tail Recursion.
* load: Load.
* load-foreign: Loading Unix Object Files.
* lookup-host-entry: Host Addresses.
* make-alien: Alien Dynamic Allocation.
* make-breakpoint: Breakpoints.
* make-fd-stream: File Descriptor Streams.
* make-object-set: Object Sets.
* make-remote-object: Remote Objects.
* make-wire: Making Your Own Wires.
* object-set-event-handler: With Object Sets.
* object-set-operation: Object Sets.
* open-clx-display: Using SERVE-EVENT with the CLX Interface to X.
* parse-time: Time Parsing and Formatting.
* preprocess-for-eval: Debug-functions.
* process-alive-p: Process Accessors.
* process-close: Process Accessors.
* process-core-dumped: Process Accessors.
* process-error: Process Accessors.
* process-exit-code: Process Accessors.
* process-input: Process Accessors.
* process-kill: Process Accessors.
* process-output: Process Accessors.
* process-p: Process Accessors.
* process-pid: Process Accessors.
* process-plist: Process Accessors.
* process-pty: Process Accessors.
* process-status: Process Accessors.
* process-status-hook: Process Accessors.
* process-wait: Process Accessors.
* profile: Profile Interface.
* remote: Remote Evaluations.
* remote-object-eq: Remote Objects.
* remote-object-local-p: Remote Objects.
* remote-object-p: Remote Objects.
* remote-object-value: Remote Objects.
* remote-value: Remote Evaluations.
* remote-value-bind: Remote Evaluations.
* remove-all-oob-handlers: Out-Of-Band Data.
* remove-fd-handler: Using SERVE-EVENT with Unix File Descriptors.
* remove-oob-handler: Out-Of-Band Data.
* report-time: Profile Interface.
* required-argument: Compile Time Type Errors.
* reset-time: Profile Interface.
* return-from-frame: Frames.
* run-program: Running Programs from Lisp.
* sap+: System Area Pointers.
* sap-alien: Alien Coercion Operations.
* sap-int: System Area Pointers.
* sap-ref-16: System Area Pointers.
* sap-ref-32: System Area Pointers.
* sap-ref-8: System Area Pointers.
* save-lisp: Saving a Core Image.
* search-list: Search Lists.
* search-list-defined-p: Search Lists.
* send-character-out-of-band: Out-Of-Band Data.
* serve-all-events: The SERVE-EVENT Function.
* serve-event: The SERVE-EVENT Function.
* set-floating-point-modes: Accessing the Floating Point Modes.
* signed-sap-ref-16: System Area Pointers.
* signed-sap-ref-32: System Area Pointers.
* signed-sap-ref-8: System Area Pointers.
* slot: Alien Access Operations.
* source-path-context: Source Translation Utilities.
* time: Additional Timing Utilities.
* top-frame: Frames.
* trace: Function Tracing.
* unencapsulate: Encapsulation Functions.
* unprofile: Profile Interface.
* untrace: Function Tracing.
* var: Variable Access.
* wait-until-fd-usable: Using SERVE-EVENT with Unix File Descriptors.
* wire-fd: Making Your Own Wires.
* wire-force-output: Remote Evaluations.
* wire-get-byte: Untagged Data.
* wire-get-number: Untagged Data.
* wire-get-object: Tagged Data.
* wire-get-string: Untagged Data.
* wire-output-byte: Untagged Data.
* wire-output-number: Untagged Data.
* wire-output-object: Tagged Data.
* wire-output-string: Untagged Data.
* wire-p: Making Your Own Wires.
* with-alien: Local Alien Variables.
* with-clx-event-handling: Without Object Sets.
* with-compilation-unit: Compilation Units.
* with-enabled-interrupts: Changing Interrupt Handlers.
* with-fd-handler: Using SERVE-EVENT with Unix File Descriptors.
* with-interrupts: Changing Interrupt Handlers.
* without-hemlock: Changing Interrupt Handlers.
* without-interrupts: Changing Interrupt Handlers.